MacFormat 1996 January

home *** CD-ROM | disk | FTP | other *** search

/ MacFormat 1996 January / macformat-033.iso / mac / Shareware City / Developers / ABox.v1.8 / ABox info... / About the ABox... / Programming Info / 3-Special Properties < prev next >

Wrap

Text File | 1995-01-12 | 11.8 KB | 294 lines | [TEXT/R*ch]

Programming Info: Special Properties Extra Functionality The ABox can be configured as: • a normal, modal about-box • a moveable modal about-box • a modeless about-box and, additionally, can be implemented as a modal, moveable modal, or modeless splash screen that: • disappears upon mouse/key click • disappears after a specific time • disappears when the application tells it to When operating as a splash-screen, the ABox cannot be browsed. That is, the user cannot scroll through the topics, move from slide to slide, etc. Depending upon the configuration of the ABox (as specified by the host application), the user might be able to drag items from the ABox window, click on titles to hear the Speech Manager, move the window about the desktop, or move between application layers. Programmers take note: use a configuration that makes the most sense for your application and implementation of the ABox--sometimes modeless splash-screens might not be a good thing. ============ More Details: Properties Properties are the driving customization mechanism behind all of the ABox features. Borrowed from the model set forth by the PlainTalk and Text-to-Speech subsystems of the MacOS, it provides a very small and simple API for controlling the behavior of the software. The ABox class, which is what your application/code interacts with, provides a pair of methods to get and set the various properties of the ABox. OSErr ABox::GetProperty (ABProperty prop, void *ptr, long *ptrSize); OSErr ABox::SetProperty (ABProperty prop, void *ptr, long ptrSize); The list of properties is provided in the ABox.h file; the code fragment below is an example of how to setup some of the various There are several special error codes that the GetProperty/SetProperty methods can return to your code; these are listed below: Error Code Description ------------------------------------------------------------------------ kABPropertyUnknown the named property cannot be found within the ABox; be sure to use only the predefined property name constants, provided in the list found within this documentation kABPropertyBadStorage the property value could not be stored for your use. This typically happens when a dynamic memory allocation fails and the ABox code has to abort the property operation; it can also occur when the calling code provides inadequate storage (such as indicating that the return-value buffer has a negative length). kABPropertyNullStorage the property could not be returned to the calling code because no storage was provided for the return value. kABPropertyReadOnly the property that you attempted to adjust is a read-only value that cannot be altered. Read-Only properties are usually internal ABox properties that the caller is allowed to examine, but not alter. ========================================================================== Named Property List Every property has a name and a size constant, both of which are provided to insulate you and your code from the actual implementation of the property data whenever possible. You should always use the predefined constants whenever possible, since the values "behind the scenes" are always subject to change. Property Description ------------------------------------------------------------------------ kABoxWindow READ-ONLY kABoxWindowSize (sizeof(WindowPtr)) kABoxHomeFolder kABoxHomeFolderSize The home folder property is used to "point" the ABox at a folder tree. The property has a default value corresponding to an invalid FSSpec, thereby describing an invalid folder tree. If you wish to provide a folder tree for the ABox, set this property with an FSSpec of your design. kABoxSplashTimeSeconds kABoxSplashTimeSecondsSize The splash time property is used to set the splash-screen capabilities of the ABox. There are several pre-defined splash-time values available for your use (the default value is kABoxNoSplash): kABoxNoSplash don't act as a splash screen kABoxWaitForClickSplash splash screen that needs a click or a return-key-hit to be dismissed kABoxWaitForApplicationSplash splash screen dismissed by the application and not by the user Additionally, any positive non-zero value can be used as the value of the splash-time property to indicate a splash screen that exists for that many seconds. kABoxNumberOfTopics READ-ONLY kABoxNumberOfTopicsSize The number of topics property represents the total number of topics in the ABox. This value includes the topics found within the application resource fork and those found in the home folder tree, if provided. kABoxFirstTopicNumber kABoxFirstTopicNumberSize This property is used to indicate to the ABox which topic in the topic list should be the 'active topic' when the ABox is displayed. The default value of 1 indicates the first topic in the list (traditionally the topic found within the application resource fork, if present). By changing this property you can alter which topic the ABox will display first when made visible, a useful feature for context-sensitive operations. kABoxCurrentTopic READ-ONLY kABoxCurrentTopicSize This property represents the currently selected and shown (ie: highlighted and displayed) topic kABoxFirstSlideNumber kABoxFirstSlideNumberSize This property is used to indicate to the ABox which slide in the first-topic will be shown when the ABox is displayed. The default value of 1 indicates the first slide of the first topic in the list (traditionally the topic found within the application resource fork, if present). By changing this property you can alter which slide of the first topic the ABox will display first when made visible, a useful feature for context-sensitive operations. kABoxAppResFile kABoxAppResFileSize This property is used to inform the ABox which resource fork belongs to the application. Since the ABox deals with many files, supports the Thread Manager, and the application can have many resource forks open, this property is vitally important to the correct operation of your programming. The default value is that of the Toolbox call CurResFile() when the ABox is first instantiated. kABoxUpdater kABoxUpdaterSize This property is used by your programming to provide a callback function for your application's update methods when the ABox is up and running. This is especially important when implementing any form of modal ABox, since there are documented issues with the functioning of the Dialog Manager and update events for other windows/applications. You should set the property to a function/method of your designs, being of type UpdateWindowUPP. This method/function will be called whenever the ABox needs to pass along an update event to your code. kABoxModalIndicator kABoxModalIndicatorSize This property is used to control whether the ABox should behave as a modal, moveable modal, or modeless window. The default is kABoxModal. The predefined values for your use are: kABoxModal kABoxMoveableModal kABoxModeless kABoxAppNameAndVersion kABoxAppNameAndVersionSize This property represents a string, provided by your code, that can be used to display anything; traditionally it is used to display the application name and version, and perhaps date, in the appropriate area of the ABox. kABoxTextFont kABoxTextFontSize This property is used to control the font used in the ABox. The property is of type ABoxTextFontType, and has a default value of kABtextFont. kABoxTextSize kABoxTextSizeSize This property is used to control the font size used in the ABox. The property is of type ABoxTextSizeType, and has a default value of kABtextSize. kABoxTextFace kABoxTextFaceSize This property is used to control the font style used in the ABox. The property is of type ABoxTextFaceType, and has a default value of kABtextFace. kABoxLastEvent kABoxLastEventSize This property, odd as it is, allows access to or the setting of the last EventRecord. This is primarily an internally used property, and, as a general rule, should not be used by your code. kABoxListHandle READ-ONLY kABoxListHandleSize This property allows access to the list of topics within the ABox. This is primarily an internally used property, and, as a general rule, should not be used by your code. kABoxWindowTitle kABoxWindowTitleSize This property represents a string to be used for the title of the ABox window, seen only when the ABox is implemented as a moveable modal or modeless window. kABoxThreadsHandler kABoxThreadsHandlerSize This property is used by your programming to provide a thread function for your application when Thread Manager support is provided. You should set the property to a function/method of your designs, being of type DoThreadsUPP. This method/function will be called whenever the ABox needs to pass thread control to your code. kABoxInBackground READ-ONLY kABoxInBackgroundSize This property can be used to determine if the ABox is in the background. kABoxIsFinished READ-ONLY kABoxIsFinishedSize This property can be used to determine if the ABox is finished and should be dismantled, useful only when implementing the ABox as a modeless window. kABoxReportMemory kABoxReportMemorySize This property is a boolean indicator that controls whether the ABox should provide a memory usage display in the corner of the ABox. This is useful for debugging, or if you just want to load the ABox window up with various technoid-geeky details. The default is false. kABoxUseSpeechMgr kABoxUseSpeechMgrSize This property is a boolean indicator that controls whether the ABox should provide Speech Manager support. If set to true, the ABox will allow the Speech Manager to speak the slide title when the user clicks on the that element. Additionally, if your application is built with the symbol SPEAK_ERROR set to 1, the ABox will attempt to speak any errors that occur instead of just beeping. The default is true if the Speech Manager is present. kABoxUseDragMgr kABoxUseDragMgrSize This property is a boolean indicator that controls whether the ABox should provide Drag Manager support. If set to true, the ABox will allow the user to drag various TEXT and PICT elements from the ABox window to other Drag Manager savvy applications. The default is true if the Drag Manager is present. kABoxUseSoundMgr kABoxUseSoundMgrSize This property is a boolean indicator that controls whether the ABox should provide Sound Manager 3 support. If set to true, the ABox will play all sounds in an asynchronous and Sound Manager 3 compatible fashion. The default is true if the Sound Manager 3 is present.